|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.google.common.collect.MapMaker
public final class MapMaker
A ConcurrentMap
builder, providing any combination of these features:
soft or weak keys, soft
or weak values, timed expiration, and on-demand computation of values. Usage
example:
@code ConcurrentMap<Key, Graph> graphs = new MapMaker() .concurrencyLevel(32) .softKeys() .weakValues() .expiration(30, TimeUnit.MINUTES) .makeComputingMap( new Function<Key, Graph>() { public Graph apply(Key key) { return createExpensiveGraph(key); } });}These features are all optional;
new MapMaker().makeMap()
returns a
valid concurrent map that behaves exactly like a ConcurrentHashMap
.
The returned map is implemented as a hash table with similar performance
characteristics to ConcurrentHashMap
. It supports all optional
operations of the ConcurrentMap
interface. It does not permit null
keys or values. It is serializable; however, serializing a map that uses soft
or weak references can give unpredictable results.
Note: by default, the returned map uses equality comparisons (the
equals
method) to determine equality for keys
or values. However, if weakKeys()
or softKeys()
was
specified, the map uses identity (==
) comparisons instead for keys.
Likewise, if weakValues()
or softValues()
was specified,
the map uses identity comparisons for values.
The returned map has weakly consistent iteration: an iterator over one of the map's view collections may reflect some, all or none of the changes made to the map after the iterator was created.
An entry whose key or value is reclaimed by the garbage collector immediately
disappears from the map. (If the default settings of strong keys and strong
values are used, this will never happen.) The client can never observe a
partially-reclaimed entry. Any Map.Entry
instance retrieved
from the map's entry set is snapshot of that
entry's state at the time of retrieval.
new MapMaker().weakKeys().makeMap()
can almost always be used as a
drop-in replacement for WeakHashMap
, adding concurrency,
asynchronous cleanup, identity-based equality for keys, and great
flexibility.
Constructor Summary | |
---|---|
MapMaker()
Constructs a new MapMaker instance with default settings,
including strong keys, strong values, and no automatic expiration. |
Method Summary | ||
---|---|---|
MapMaker |
concurrencyLevel(int concurrencyLevel)
Guides the allowed concurrency among update operations. |
|
MapMaker |
expiration(long duration,
TimeUnit unit)
Specifies that each entry should be automatically removed from the map once a fixed duration has passed since the entry's creation. |
|
MapMaker |
initialCapacity(int initialCapacity)
Sets a custom initial capacity (defaults to 16). |
|
|
makeComputingMap(Function<? super K,? extends V> computingFunction)
Builds a map that supports atomic, on-demand computation of values. |
|
|
makeMap()
Builds the final map, without on-demand computation of values. |
|
MapMaker |
softKeys()
Specifies that each key (not value) stored in the map should be wrapped in a SoftReference (by default, strong references are used). |
|
MapMaker |
softValues()
Specifies that each value (not key) stored in the map should be wrapped in a SoftReference (by default, strong references are used). |
|
MapMaker |
weakKeys()
Specifies that each key (not value) stored in the map should be wrapped in a WeakReference (by default, strong references are used). |
|
MapMaker |
weakValues()
Specifies that each value (not key) stored in the map should be wrapped in a WeakReference (by default, strong references are used). |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
public MapMaker()
MapMaker
instance with default settings,
including strong keys, strong values, and no automatic expiration.
Method Detail |
---|
public MapMaker initialCapacity(int initialCapacity)
IllegalArgumentException
- if initialCapacity
is negative
IllegalStateException
- if an initial capacity was already setpublic MapMaker concurrencyLevel(int concurrencyLevel)
IllegalArgumentException
- if concurrencyLevel
is nonpositive
IllegalStateException
- if a concurrency level was already setpublic MapMaker weakKeys()
WeakReference
(by default, strong references are used).
Note: the map will use identity (==
) comparison to
determine equality of weak keys, which may not behave as you expect. For
example, storing a key in the map and then attempting a lookup using a
different but equals
-equivalent key will
always fail.
IllegalStateException
- if the key strength was already setWeakReference
public MapMaker softKeys()
SoftReference
(by default, strong references are used).
Note: the map will use identity (==
) comparison to
determine equality of soft keys, which may not behave as you expect. For
example, storing a key in the map and then attempting a lookup using a
different but equals
-equivalent key will
always fail.
IllegalStateException
- if the key strength was already setSoftReference
public MapMaker weakValues()
WeakReference
(by default, strong references are used).
Weak values will be garbage collected once they are weakly reachable.
This makes them a poor candidate for caching; consider
softValues()
instead.
Note: the map will use identity (==
) comparison to
determine equality of weak values. This will notably impact the behavior
of containsValue
,
remove(Object, Object)
, and
replace(K, V, V)
.
IllegalStateException
- if the key strength was already setWeakReference
public MapMaker softValues()
SoftReference
(by default, strong references are used).
Soft values will be garbage collected in response to memory demand, and in a least-recently-used manner. This makes them a good candidate for caching.
Note: the map will use identity (==
) comparison to
determine equality of soft values. This will notably impact the behavior
of containsValue
,
remove(Object, Object)
, and
replace(K, V, V)
.
IllegalStateException
- if the value strength was already setSoftReference
public MapMaker expiration(long duration, TimeUnit unit)
duration
- the length of time after an entry is created that it should be
automatically removedunit
- the unit that duration
is expressed in
IllegalArgumentException
- if duration
is not positive
IllegalStateException
- if the expiration time was already setpublic <K,V> ConcurrentMap<K,V> makeMap()
MapMaker
instance, so it
can be invoked again to create multiple independent maps.
K
- the type of keys to be stored in the returned mapV
- the type of values to be stored in the returned map
public <K,V> ConcurrentMap<K,V> makeComputingMap(Function<? super K,? extends V> computingFunction)
Map.get(java.lang.Object)
either returns an already-computed value for the given
key, atomically computes it using the supplied function, or, if another
thread is currently computing the value for this key, simply waits for
that thread to finish and returns its computed value. Note that the
function may be executed concurrently by multiple threads, but only for
distinct keys.
If an entry's value has not finished computing yet, query methods besides
get
return immediately as if an entry doesn't exist. In other
words, an entry isn't externally visible until the value's computation
completes.
Map.get(java.lang.Object)
on the returned map will never return null
. It
may throw:
NullPointerException
if the key is null or the computing
function returns null
ComputationException
if an exception was thrown by the
computing function. If that exception is already of type
ComputationException
, it is propagated directly; otherwise it is
wrapped.
Note: Callers of get
must ensure that the key
argument is of type K
. The get
method accepts Object
, so the key type is not checked at compile time. Passing an
object of a type other than K
can result in that object being
unsafely passed to the computing function as type K
, and unsafely
stored in the map.
If Map.put(K, V)
is called before a computation completes, other
threads waiting on the computation will wake up and return the stored
value. When the computation completes, its new result will overwrite the
value that was put in the map manually.
This method does not alter the state of this MapMaker
instance,
so it can be invoked again to create multiple independent maps.
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |